home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware Grab Bag
/
Shareware Grab Bag.iso
/
007
/
bled15.arc
/
BLED.DOC
< prev
next >
Wrap
Text File
|
1987-01-26
|
32KB
|
701 lines
DOCUMENTATION for BLED version 1.5
by Ken Goosens, 5020 Portsmouth Road, Fairfax, VA 22032
25 January 1987
**********************************************************************
* BLED is copyrighted by its author. BLED can be freely distributed *
* by non-profit organizations and bulletin boards. BLED cannot be *
* distributed commercially nor included in any commercial product *
* with the explicit written consent of the author. Individuals *
* are encouraged to give free copies to other individuals. *
* All rights to the code are held by the author and any use *
* or modification of the code requires permission of the author. *
**********************************************************************
BLED is supported by its author. Individuals are encouraged to report
bugs, suggest enhancements, or, preferably, to make improvements to
the code available to others through the author.
BLED should be distributed with the following files:
BLED.DOC - this file
BLED.EXE - compiled, executable code
BLED.BAS - main program source code
UTILBLED.BAS - separately compiled subprograms used in BLED
BLED uses assembler subroutines from the fine library ADVBAS by
TOM HANLIN. The author has paid Tom Hanlin for rights to use his
code.
CONTENTS
What is BLED
What Use is BLED
What are the Advantages of BLED
New Features of BLED
How Does BLED Work
How do you Identify Lines
Line Number Merging
How to Invoke BLED
How BLED Runs
The Major BLED Functions
CONFIGURE
FILE COMPARE
LINE MERGE
MERGE
Stylistic Considerations
How to Recompile BLED
What is BLED
BLED is a Batch Line EDitor. Editor - because it changes text files.
Line - because it operates on entire lines of text rather than
individual characters or phrases. And batch - because the changes to
be made are not specified interactively, but are pre-specified in a
file describing the changes, which is created outside of BLED.
What Use is BLED?
BLED is most useful when different people have to communicate changes
to a text file that they jointly maintain. The typical use of BLED is
for producing modifications to source code for programs. Interactive
Microsoft BASIC has long had a MERGE command which functions like
BLED. It inserts, deletes, and replaces lines based on line numbers.
Other public domain programs would compare two BASIC programs and
produce a merge file to convert one to the other using the merge
command. BLED is a generalized program that combines these two
functions.
What are the Advantages of BLED?
o Lines of text do not have to be numbered.
This means that BLED will work with source code that allows lines of
code to have no numbers, including Mircosoft QuickBASIC, as well as
Pascal and other languages.
o Comment lines are supported.
BLED comment lines are completely ignored when merging. This means
that documentation can be included right inside a BLED merge file.
One of the disadvantages of the BASIC merge command was that the only
type of line possible was BASIC code, so that documentation for a
merge always had to be included in a separate file.
o Logical lines can span multiple physical lines.
One of the more disagreeable features of old BASIC was that a single
line of code (i.e. a line beginning with a number) had to be on one
physical line. Newer languages like QuickBASIC support a
line-continuation character (e.g the underscore) that allows the same
logical line to span multiple physical lines. This greatly improves
the readability of source code by allowing grouping by indentation.
BLED recognizes and supports logical lines.
o Can be run batch from DOS, or interactively.
Commands telling BLED what to do can be specified as DOS arguments,
and BLED has a batch mode in which it will run without further prompts
and return automatically to DOS. BLED will prompt for any arguments
it needs which are not specified.
o Configurable.
BLED comes pre-set to work with Microsoft QuickBASIC, but can be
configured to work with different languages.
New Features of BLED
BLED 1.5 has two major enhancements, some bug fixes, and some
cosmetic changes.
o A new option to support preserving BLED comments.
On a merge, BLED comment lines were always eliminated and there
was no way to put temporarily comments on changes as source code
comments. Now there is a configuration parameter that will cause
BLED comment lines to be converted to a specially formatted source
code comment lines in a merge and, conversely, convert these special
source code comments to BLED comments when doing a file compare to
produce a merge. This change allows programmers to work with equal
fecility with merges or directly on the full program and readily
document changes and yet easily remove these temporary comments
when the code is put into production.
o BLED is about 33% faster because it has been recompiled
under QUICKBASIC 2.0.
o The automatic documentation in a file compare has been
enhanced to include the date and file size of the old
version of the code so that there is no ambiguity about
what version of the code the new merge goes against.
o A bug has been fixed that caused the character used for
a source code remark not to be read in properly from a
configuration file.
o A bug has been fixed that caused the maximum number of
physical lines allowed in a logical line not to be read
in properly from a configuration file.
o Status line reports now use a mixture of upper and lower
case rather than all upper case. This improves readability
and reserves all upper case words for special emphasis.
o When a file is missing and the proper name is entered,
the status line is now properly restored.
o When the user Quits in interactive mode, the cursor is
left at the bottom of the screen rather than in the middle
of previous text.
o A parameter has been added which was in the code but missing
from the documentation. Other parts of the documentation
have been added or made more thorough, including a statement
of distribution rights and how to recompile BLED.
History of Other Changes
BLED 1.4 has one major change. Output is now internally buffered.
Before, every line was written out immediately. Now up to 100 lines
are held internally before writing. This dramatically reduces the
number of disk i/o's and reduces the head movement, usually making
the program faster. My test showed a 12% improvement with RBBS.
The only other change is that the default maximum number of lines
between line numbers is now 400 rather than 200.
BLED 1.3 fixes a bug. If a line begins with a comment other than in
column 1 and ends with a line continuation character (e.g. source code
commented out), BLED would get not correctly identify the line as a
comment and would get an illegal function call.
BLED 1.2 has two two features: (1) autodocumenting merge, and (2) test
run mode.
AUTODOCUMENTING. When you do a file compare to produce a merge, BLED
produces a header on what files were used to make the merge and date
and time stamps the merge. Also, BLED produces a header comment for
each change indicating whether the line is being INSERTED, DELETED, or
REPLACED (changed). Also, for replacement lines longer than one line,
BLED will insert a comment marking the first different line.
TEST MODE. There is a new "T" (for Test) parameter. This limits the
run to a specificed number of logical lines in the master file. You
will not normally use this parameter.
How Does BLED Work?
Like a block editor. Think of how you would work with a full screen
text editor, if you had to work from the top to the bottom of the
file. You basically do two things:
o Mark a block of lines.
o Say what to do with the block - either keep, delete, or replace
by another block of code; or insert a block of code.
BLED has a BLOCK command to identify the block of text, followed by a
disposition command of KEEP, DELETE, REPLACE, or INSERT. This is
BLED's general MERGE.
How do You Identify Lines?
You have to specify what blocks of lines you want to work with. There
are three ways.
o By physical line number.
The absolute physical line numbers are 1,2,3,etc. for each line of
text. Relative lines can also be specified, e.g. from the current
position in the file forward three lines.
o By line labels.
Line labels are identifiers or names for lines. BLED supports both
numeric line labels (it calls them label numbers) and alphanumeric
labels (simply labels). BLED ASSUMES THAT A LINE LABEL OCCURS ONLY AS
THE FIRST WORD ON A LINE. Some languages allow labels to be put in
the middle of a physical line, but this is bad practice because
interior labels are hard to find.
o By strings.
Strings are just sequences of characters that can occur inside lines.
So, in BLED, a block can be identified as beginning or ending with an
absolute or relative line number, a line label, or a string. And so a
block can be defined as
the first five lines
everything between label-1 and label-2
from line 50 to label-1
from label-1 to the line with "HELP" in it
Line Number Merging
BLED also supports a more specialized merge much like the BASIC
merge. Details are given below. This line merge mode is just like
the BASIC merge command except that logical blocks of physical lines
replace the single physical line, and comment lines are supported.
BLED supports the specialized line number merge because the
assumptions greatly simplify the merge files. No special BLED
commands are required: no blocks, no block dispositions. To insert a
line, just give it a line number between the original line numbers.
To delete, put only the line number in the merge file. To replace,
use the same line number.
The BLED line number merge treats all lines between line numbers as a
single block, i.e. as if they are one single logical line, even if
they are multiple physical and logical lines. For example, in the
BASIC code
200 X = X+1
IF X>5 THEN_
Y=0
210 Y = Y+1
you might think that you could delete the first line 200 by having
"200" alone in the merge. In fact, the first three lines would be
deleted rather than the first only.
How to Invoke BLED
BLED is invoked at DOS by typing
BLED[/options] [spec-1] [spec-2] [spec-3] [spec-4] [spec-5]
where a spec has the format [drive:][\path\][filename]
Everything in brackets is optional and may be omitted. The options
after BLED are
/B - run batch. Means to ask no questions and automatically
return to DOS when done. Must be used with one of
following options and requires first three specs.
/F - file compare. Means to produce a merge file which will
transform spec-1 (old version) into spec-2. Output is
spec-3.
/L - line number merge. Do a merge of spec-2 into spec-1,
based on line number identifiers in both files,
outputting to spec-3.
/M - general merge based on BLED commands. Into spec-1
merge spec-2, producing spec-3.
/T=XXX - test mode. Do not process all line from master (first)
file. Instead, end the run after processing XXX (a
number) of logical lines in the master file. Used
mainly for testing BLED. So you can run against large
real files without having to create smaller samples.
Note: /F,/L,/M options are incompatible and at most one can be
specified. BLED checks for consistency and required parameters and
will abort with an error message and help. Optional parameters not
specified at DOS are supplied using full screen prompts.
Spec-4 is used when you want to override the default warning file name
(WARNING is the default configuration value). BLED keeps appending to
the warning file as long as you continue to run within it. Each time
you reenter BLED from DOS, however, BLED will begin overwriting the
warning file. The override is useful if you want to preserve previous
warning files.
Spec-5 is for overriding the default configuration file name of
BLED.CFG.
Note: the meaning of the first three file specs is different for the
/F option. Merges mean
[source file] [merges] [source+merge]
But for the /F option the specs mean
[old version] [new version] [merges]
How BLED Runs
BLED makes a single pass through the original file, doing comparisons
to the second file. Therefor all references to line labels should be
in the same order they occur in the original file. BLED gives an on-
screen status report of what it is doing, the files it is using, as
well as counts of the number of records it reads and writes at the
bottom of the screen.
The Major BLED Functions
The four major BLED functions are
o CONFIGURE. General configuration parameters.
o FILE COMPARE. Create a merge file.
o LINE MERGE. Merge based on line number labels.
o MERGE. Merge using explicit BLED block and block disposition
commands.
The main menu in BLED uses the first letter of each choice.
CONFIGURE
BLED has 10 configuration parameters, which are stored in the
configuration file BLED.CFG. If no configuration file exists, BLED
uses as a default parameters suitable for QuickBASIC.
(1) Default extension for source files. If no extension is given for
source files, BLED will add this. Default for this option is
BAS. Source files include spec-1, and also spec-3 for merges and
spec-2 for file compares.
(2) Default extension for changes to source. If no extension is
given for this file, BLED will add this. Default for this option
is MRG. In merges, this applies to spec-2. In file compares,
this applies to spec-3.
(3) Character using to begin remarks in source. Default character is
the single quote ('). When looking for a line continuation
character at the end of a line, BLED will ignore all text after
the remark character.
(4) BLED phrase indicating end of block. Used with INSERT BLOCK
command. What follows is a block of code to be inserted. Tells
BLED where the code ends.
(5) Character beginning a line of BLED documentation. BLED will
completely ignore a line beginning with this character when
merging. Allows comments or documentation to be included right
in a merge file to explain changes. The character need not be in
column 1 - only the first non-blank character. Default is "*".
The documentation character should never occur as the first
character in your source text.
(6) Character at end of every alphanumeric label. Default is ":".
BLED assumes that line labels occur only as the first word in a
line. Leading spaces are ignored, so that labels can begin in
any column. This label character is used by BLED to help locate
labels. When specifying blocks in a BLED command, you need not
include the end-character. BLED knows, for example, what when
you say "LABEL LOOPER" that "LOOPER:" is what actually occurs in
the source code.
(7) Character beginning BLED commands. Default is none. BLED can
distinguish its commands from source code lines by when a command
is needed and by key phrase. If confusion might result, however,
you can specify that BLED commands begin with a character that
will never occur at the beginning of a line of text, such as
possibly "$" or "-".
(8) Whether case is ignored in alphanumeric labels. Default is yes,
so that "looper" and "LOOPER" are treated as the same.
(9) Line continuation character. One way for a logical line to span
multiple physical lines is to insert a special line continuation
character at the end of a line that logically continues on the
following line. Default is "_" (underscore). May differ in
languages other than QuickBASIC. Many other freeform languages
use a statement terminator character. Fortran puts a
continuation character in column 6, which is not supported by
BLED. (BLED can still work on FORTRAN files though.)
(10) File that warning messages are written to. From the time you
enter BLED until you exit DOS, BLED may issue warning messages
based on its file comparison or merge. These messages are
written to this file for perusal later. This way BLED can run
completely batch with no loss of information. You can nullify
these messages by making the file "NUL:" or send them to the
screen using "SCRN:". BLED will report the number of warning
messages during its operation. Sending messages to the screen
will interfere with BLED's normal report of its progress on the
screen. The default name for this warning is "WARNING".
(11) Maximum number of physical lines in a logical line. There are
several functions that require BLED to hold an entire logical
line in memory before it can decide what to do with the line.
For example, a file compare requires BLED to determine whether
there has been any change anywhere in common line numbers.
There are only so many physical lines that BLED can hold in
memory from a master or transaction file. The default is 400.
This parameter allows the user to increase that number.
(12) Preserve BLED comment lines. It is important to be able to
append notes to source code to explain changes. These can
be left permanently in the code by making them source code
comments. But often it is desired to leave comments in the
text only temporily. The only facility for doing this in
versions of BLED prior to 1.5 was to include special BLED
comment lines in a merge file which would be stripped out when
a merge was done.
For people who prefer to work with the full
source code rather than merges, and then to do a BLED file
compare against the original version to produce a BLED merge,
the explanations of changes got stripped and there was no good
way to add in temporary comments while making changes. The
parameter to preserve BLED comment lines remedies these problems.
It will cause BLED comment lines to be kept as a specially formatted
source code comment in a merge. The BLED comment lines will be
"floated" up to the top of the line number and the BLED comment
symbol (* by default) will be replaced by the source code comment
symbol (' by default) followed by "<" with the BLED comment symbol
followed by ">". For example, "* Corrects spelling of VARIABLE"
becomes "'<*> Corrects spelling of VARIABLE".
Conversely, this parameter will cause source code comments in
the proper format to be converted to BLED comment lines in a
file compare that produces a merge. This allows programmers who
work directly with the full source to insert temporary comments.
For example, "'<*> Moved here from line 830" becomes "* Moved here
from line 830". By running this BLED generated merge with this
option off, so that BLED comment lines are stripped, the temporary
commentary goes deleted.
The default for this parameter is "N", so that persons desiring
to preserve BLED comments must edit and save the configuration.
FILE COMPARE
The function of this module is to produce a BLED merge file that will
convert an old version of a file to a new, modified version. All that
is in the merge are the necessary changes. This is a very complex and
difficult programming task which is only partially implemented in the
current version. The file comparison will only work for source with
line number labels. Essentially, the assumption is that the line
number labels are ordered from low to high in both versions of the
file. A comparison utility must have some way to identify lines.
Ideally, this constraint should be relaxed to apply to alphanumeric
labels with no assumptions about order. Please send me your ideas or
code changes if you think you can solve this problem. So, the ONLY
TYPE OF MERGE FILE THAT FILE COMPARISON WILL PRODUCE IS ONE FOR LINE
MERGING, and not for general merging.
Operationally, this means that if you are not using line numbers in
your source code, you should make your code changes directly in a
merge file, and apply the merge file to produce the modified code. If
you directly change the old version, there will be no way to isolate
just the changes later.
NOTE: the BLED file compare is NOT A GENERAL FILE COMPARE. General
file compares, like the DOS utility, compare two files by relative
byte position with a file. BLED does a logical line by logical
line compare. Apply the BLED file compare ONLY TO COMPILEABLE SOURCE
CODE, otherwise the result will be unpredictable.
LINE MERGE
This option is a generalization of the BASIC merge command. The
assumptions are that
o the lines of code are numbered at the beginning of a line.
o Physical lines of text are to be blocked from a line number up to
the next line number. The merge operates only on such blocks as
a unit.
o The line numbers are ordered from low to high in both the source
and merge file.
o Lines in the source not in the merge file are to be kept, lines
in the merge not in the source are to be inserted, and lines in
both are to be replaced by the line (i.e. block) in the merge
file.
o Lines in the merge file with only a line number are to be deleted
from the source file.
o The merge maintains the low to high line number order.
MERGE
The general merge in BLED allows merges even when there are no line
numbers. The BLED commands are BLOCK, INSERT, DELETE, REPLACE, and
KEEP. Each of these commands can be abbreviated by their first letter
(e.g "B FROM LINE 1 TO LINE 5" means "BLOCK FROM LINE 1 TO LINE 5").
The syntax is
BLOCK [FROM] [linetype] lineid [TO/UPTO/THRU] [linetype] lineid
[block disposition] [lineid]
where [linetype] is LINE/LABEL/LABEL#/STRING.
The BLOCK command is for marking a block of text in the source file
(spec-1). It must specify where the block begins and ends. The first
three phrases after BLOCK identify the beginning, the last three the
end. All phrases enclosed in brackets are optional. LINE is the
default linetype if none is specified.
Linetype has four options.
o LINE means the physical line number, either absolute or relative.
The lineid distinguishes the two. Absolute line numbers are positive
integers, relative line numbers are "*+n", where n is a positive
integer.
o LABEL means an alphanumeric label.
o LABEL# means a numeric line label (a positive integer).
o STRING means a string of characters.
LABELS must be the first word on a line, STRINGS can occur anywhere in
a line.
Lineid matches with the linetype. LABEL and STRING require a word
with any characters. LABEL# requires a positive integer. And line
requires either a positive integer, or the string "*+" to mean the
current line in the text file plus" a positive number, or the word
"END" to indicate thru the end of file.
The phrase TO and UPTO are equivalent. They mean up to but not
including. The phrase THRU means up to and include. TO is the
default if no phrase is specified.
There are three block dispositions: KEEP/DELETE/REPLACE. They tell
BLED what to do with a defined block and therefor make sense only
after a BLOCK command. DELETE deletes the block, KEEP keeps it.
REPLACE [BLOCK/n]
This replaces a defined block with another. The "n" means that the
next n physical lines go in place of the defined block. And BLOCK
means that all following lines up to the end-block phrase are the
replacements.
Another BLED command is to insert new lines.
INSERT [BLOCK/n]
This means to insert a block of lines at the current position in the
source file, i.e. just before the current line that has been read.
The "n" means to insert the following n physical lines. The BLOCK
means to take all following lines up to the end-block phrase.
EXAMPLES
(SOURCE) (MERGES)
CALL INITIALIZE BLOCK FROM LINE 1 TO STRING OPENFILES
GOSUB OPENFILES REPLACE 1
LOOPER: CALL HELP
IF X=1 THEN GOTO ALLDONE: BLOCK FROM LINE * THRU LABEL ALLDONE
X = X+1 KEEP
GOTO LOOPER INSERT BLOCK
ALLDONE: CLOSE
END ENDBLOCK
(RESULT)
CALL HELP
GOSUB OPENFILES
LOOPER:
IF X=1 THEN GOTO ALLDONE:
X = X+1
GOTO LOOPER
ALLDONE:
CLOSE
END
(SOURCE) (LINE MERGE)
110 IF GOT.COMMAND THEN_ 115 NO.HELP = -1
IF NO.HELP THEN_ 150 IF HELPFUL THEN_
PRINT "SORRY" WHILE X>5 AND NOT EOF(2):_
120 GOSUB CHKFILES GOSUB CHECKER:_
150 IF HELPFUL THEN_ WEND
WHILE X>5:_ 200
GOSUB CHECKER:_ 220 END
WEND
200 IF X>10 THEN X=12
(RESULT)
100 IF GOT.COMMAND THEN_
IF NO.HELP THEN_
PRINT "SORRY"
115 NO.HELP = -1
120 GOSUB CHKFILES
150 IF HELPFUL THEN_
WHILE X>5 AND NOT EOF(2):_
GOSUB CHECKER:_
WEND
220 END
Stylistic Considerations
A good merge file includes the following information at the top of the
file.
o author
o date of merge
o what merge is to be applied to
o how to apply the merge (line number merge, general merge?)
o a list of the general fixes or enhancements made, listed in order
of most to least important coupled.
In the body of the merge the following documentation should be
included.
o a line by line explanation of the changes made stating what is
changed and why. The explanation should precede the line.
o lines should be grouped together if they implement a common
function.
A Model Merge File
*****************************************************************
* EXAMPLE.MRG *
* by Ken Goosens Jan 1, 1986 *
* *
* to be applied to BLED.BAS version 1.1 *
* using the general merge of BLED.EXE *
* *
* This merge makes two changes: *
* (1) the defaults when no configuration exists are changed *
* to be appropriate for TURBO Pascal rather than *
* QuickBASIC. *
* (2) The warning message when no configuration file exists *
* is changed to beep and delay for 3 seconds rather *
* than quietly and hurriedly display. *
*****************************************************************
* reset extensions for original and new files to "PAS"
BLOCK FROM LABEL USEDEFAULTS TO STRING ENDBLK
REPLACE BLOCK
USEDEFAULTS:
DEORIGFILE$ = "PAS"
DEBTCHCMDS$ = "MRG"
DENEWFILE$ = "PAS"
ENDBLOCK
* Change call from EXPLAIN to EXPERR
BLOCK FROM LABEL ERROPEN THRU STRING CALL
REPLACE BLOCK
ERROPEN:
X$ = "Error"+STR$(ERR)+" opening file "+FF$
CALL EXPERR (X$)
ENDBLOCK
How to Recompile BLED
BLED is written in QuickBasic and is distributed with the source
code. People wishing to modify or fix the source code can recompile
the code as follows.
QB UTILBLED /G/O;
QB BLED ,,/G/O/X;
LINK BLED+UTILBLED,,NUL.MAP,advbas
